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Intro ducti on 



The AUGMENT file system evolved from the MLS file systei» This 
document updates the HLS file decumentlon In journal Item 
C27292»>* The updates reflect the changes made to the MLS file 
system to create the AUGRE^T file system. 
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AUGHEMT operates on a heirarchical § randoRt file system with 
several unique features evolved over the years that make possible 
the efficient online Interaction used by the OAD cosjiuunl ty • 
Having Information stored Mithin separate structure antS data 
blocks aids In rapid movement within and between AUSMEWT files* a 
"partial copy" locking mechanism provides security against 
atteffipted modification of a file by more than one user at the saire 
time and provides a high degree of backup security against system 
failure or user error* This appendix Includes a technical 
description of the file systeru as well as a discussion of 
iBotlvatIng factors leading to Its Implementatl on» The design of 
the file system provides roosi for further extenslonst some of 
which are also exa wined* 
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Discussion of the heirarchical structure of AUGHEIMT files at a 
user level t as well as a description of the user comiRands that 
permit moveiRent through the filest may be found In tl3* 

This appendix is a revision of an earlier document which described 
the HLS file system as of January* 1976 and Is current to August 
1980. The January 197fe additions to the HLS file system ♦ Included 
property lists and Inferior trees* which are currently used In the 
neu grephlcs subsystem and offer great potential for the creation 
of new user entities* 

General Considerations Leading to the Current Design 

The format and structure of AlfGHEI^T files were determined by 
certain design considerations: 

It Is desirable to have virtually no limit on the size of a 
file. This peans It Is not practical to have an entire file 1n 
core when viewing or editing 1t. 

The time required for iROSt operations on a file should be 
Independent of the file length. That 1st siRall operations on a 
large file should take roughly the same time as the same 
operations on a small file. The user an<i the system should not 
be penalized for large files. 
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In executing a single editing function* there may be a 
number of structural operations. 
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A random file structure satisfies these considerations. Each file 
Is divided Into logical blocks that may be accessed In random 
o r de r • 
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An early version of the file system was Implemented on the 

XDS-940. Minor changes 1n the logical structure of the file 

system were made in the conversion of the system froin the XDS-94Q 

to the PDP-iO for two reasons: 2c 

1) The current OAD programming language* L10» 1s ^ore powerful 
than the several lanouages it replaces* HOL and the SPLs* LIO 
permits special purpose constructions anywhere 1n Its code* It 
Is a higher level language and provides greater compiler 

optimization* 

21 An effort has been si ade to further modularize the functions 
within the systeBi to ease developBient by a team of prdgraPBiRers* 

In Winter 1975 extensions to the file systesr were sisde Introduclnfi 
property lists as data eteRients at each structural node» The 
first use of this capability was in the recently developed 
graphics subsystem* Further discussldn of these chanies way be 
■■■ '■■found ■■ below #■ • ■ ■ ■•■■2d 

Reliability and the AUSMENT File Systero 3 

The reliability and security of file data both aeslnst system 

crashes and in face of the possibility of attempted sisiultaneous 

modification by more than one user were central goals in the 

design of the pVG^JHJ file system* An attemot was made to 

minimize the afnount of work which would be lost due to both 

hardware and operating system difficulties* 3a 

Unlike the sequential file systems of some editors which require 

copying large sections of a file whenever an edit Is made* AUS^^EMT 

modifies copies of pages in which structural or data changes are 

made: all data in the original file is secure and a m'nimum of 

unaffected data is copied* Still other editors maintain recent 

changes in a dynamic buffer which may not be incorporated into the 

file in the event of a system crash? In AUGKEMT* barring a major 

hardware collapset all changes other than those specified by the 

command being orocessed are present in the copied pages* Again* 

the original file is untouched* 3b 

Other techniques to assure high reliability have been used such as 

oroanizinr? the code and sequence of operations in a way to 

minimize time windows of high vulnerability* 3c 

An important problem in an online team environment such as that at 
OAD involves group collaboration on the same data files* "^he 
current file system permits multiple readers and a single writer 
to a file* The person obtaining write access to a file locks it 
in a manner described below? no other user is then permitted to 
write on the file* though they may read the original material* 
Readers without write access do not see the changes of the user 
currently editing the file until the file is explicitly "updated*" 
causing the incorporation of edits and the unlocking of the fife* 



Thus there 
writer* 



can be no conflict between the edits of siore than one 
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Details on the partial copy locking mechantsm which Implements 
these features of the AU0HENT file system are discussed below 
in section (XXXI. 

Recent Extensions to the AUGflEMT File System 
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he AUSHFJIT file system to Include a list of 

list) rather than the single textual data 
ore» These property lists are now 
T structural nodes In the saiie manner that 
ad been associated before* There 1s no 
s of data nodes t for tnstancef graphic or 
ay be possible as well combinations of data 
ode* Addit lonallyt data nodes fsay 
re in the form of "Inferior trees**# The 
upwardly compatable with the older file 
still useable on the ney file system 
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Short Technical Overview 
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This section gives a brief overview of the Implewent at ion of 

AUSHEMT files* For more detail see section CXXX)* 5a 

Block Header and Types of Blocks 5b 

An AUG^*EMT file Is made up of a file header block* and up to a 

flsced nufiber (currently 4651 of 512-word {^equals one TTNEX 

page» structure blacks Cup to 95>f and data blocks Cup to 3T0>« 5bl 

There are several types of blockst each with Its os*n structure: 5b2 

File header block— always page 0? contains general 

Inforraatlon about the file. 5b2a 



Structure (ring) blocks --contain ring elements that 

Implement the AUGHEIMT structure: there current ly Bsay be a 

Biaximum of 95 of these blockst each containing 102 five-word 

ring elements* They loay appear In file pages 6 through 100» 5b2b 

Data blocks--conta1n the data (In linked property lists 

associated with structural nodesJ of AUSHENT stateiRents; 

each data block Is composed of Individual data ele»ents made 

up of a five-word header followed by text strings or other 

data* There currently fsay be a manimum of 370 data blocks* 

They may appear In file pages 101 through 471* 5b2c 

Miscellaneous blocks--not used In the current 

ImpleiBentat 1on* 5b2d 



File Header Block 
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In each file there is a header block that contains general 
Information about that particular file* The header block 
reiRalns ir» nsemory Mhile the file 1s in use» 
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The file header is read into core by the procedure Cnlsbesrct 
ioexecf rdhdr> m This procedure checks for the validity of 
certain keyisiords* If the file is locked and has a partial 
copyt the header is read in from the partial copy* If the 
partial copy header block is invalid in the key spotsf the 
is unlocked and the header read in froa? the original file, 
that is badf the file fpay be initialized* 
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RDHDR sets the value of the FILENO-th element in the table 
FILEHEAD* FILENO is the AUGMENT file number of the file, fit is 
an index into the file status table that provides t among other 
thinfSt a correlation between JfHs for the original and partial 
copy and the single AUGMENT file nufnber). 

Procedures in (nlsbesrct filmnpfl are responsible for readingt 

fnanipulatingt creatingt garbage collectingt and storing into 
ring blocks and ring elements within those blocks t and data 
blocks and statement data blocks within them* 

Structure Blocks -- Ring Elements 
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Conceptually an AUGHEIMT file is a treem Each node has a 
pointer to its first subnode and a pointer to its successor* 
If it has no subnodet the sub-pointer points to the node 
itself. If the node has no successor t the successor pointer 
points to the node's parent* (These conventions are used to 
aid in providing a set of primitives for rapidly moving around 
In AUGHEI^T files*> Each node is currently represented by a 
ring element* These ring elesients point in turn to the first 
data block in the node»s property list- 
Structure blocks contain five-word ring eletients with a free 
list connecting those not In use* 

Data Block -- Property Lists and (Textual) Statement Data Blocks 

Data blocks are composed of variable sized elements called 
(Textual* State»ent Data Blocks ISDBs) that contain the text of 
AUSHEliT stateflfients and other types of data elements* other 
data element types are currently used in the AUSHEMT graphics 
systei though the number ©f available types and uses may be 
easily extended* All data elements have a five word header 
followed by data appropriate to the element type* Each SDB has 
this five-word header with node related Information followed by 
the text fuade up of 7-b1t ASCII characters packed five to a 
word* ^Je« data elements are allocated in the free space at the 
end of a data block page* Data elements no longer in use 
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(because of editing changes) are siarlced for garbage collection 

when the free space is exhausted* 5el 

Data elements associated with node are linked together in a 

property list. This property list may in turn have a 

structured inferior tree associated with it; the nodes on the 

inferior tree structure of a data elewentjiay also have 

associated property lists. This feature i»ay prove to be useful 

in the creation of a cofrtment entity in AUSHENT for comments 

associated with a particular /lUGMEf^T statensent. 5e2 

Statement (or String) Identifiers CSTIDSJ and Teief Pointers 5f 

A statement identifier (STID) is a data structure used within 

AUGHCMT to Identify AU6HENT statements (structural nodesi or 

strinf s « 5f 1 

If the string is in an AUGMEiT stateffientf the STID contains 

a file identifier field (STFILEI and a ring element 

identifier CSTPSID). 5fla 

The presence of a file identifier within the STID permit all 
editing functions to be carried out between files* 5flb 

Text pointers are two-word data structures used with the string 

analysis and construction features of L10» They consist of an 

STID and a character count. 5f2 

Locking Mechanism "»- Partial Copies 5g 

The AUGMENT file system under TEMEX provides a locking 

mechanism that protects against inadvertent overwrite when 

several people are working on the same file* Once a user 

starts modifying a file* it is "locked* by him against changes 

by other users until he deems his changes consistent and 

complete and issues one of the commands! Update Filet Update 

File Compactf or Delete Modifications t which unlock the file. 

A user can leave a file locked indef init ely*--this protection is 

not limited to one console session. 5gl 

yhen a file is locked (is being modified>f the user who has 

modification rights sees all of the changes that he is 

making. However* others who read the file will see it in 

its original* unaltered state. If they try to modify it? 

they will be told that it is locked by a particular user. 

Thus the users can negotiate for modification rights to the 

file. 5gla 

This feature is implenrented throufh the use of flags in the 
status table in the File Header and through the partial copy 
mechanism. 5g2 



All modifications to a file are contained Iri a partial copy 

file. These Include modified ring elements and data blocks* 5g2a 

Any file page that Is to be and that 1s not In the partial 

copy CdlsCGvered through a i#r1te pseudo-lnterrupty 1s topied 

Into the partial copy • All editing takes place there* The 

TEI^EX user-settable word In the FOB fTEWEX file data block> 

for the original file contains lock1ncp1nfor«at1on» 5g2b 

The AUSHENT Update file cosifRand merely replaces those structure 

and data pages In the original file that have been superseded 

by those In the partial copy* unlocks the filet and deletes the 

partial copy* For Update file oldt this Is done 1n the 

original file? for Update to new version » the pages are capped 

to a new file from the original or partial copy where 

necessary. The Update file compact command garbage collects 

unused space* the update file coiimand does not# SaS 

Core HanageiRent of File Space 5h 

yhen space is needed for more datat the following steps are 
taken* In ordert until enough Is found to satisfy the request 
(See Cnlsbesrct filinpf nwmgbJt (nlsbesrct filPnpt newdb>t and 
related routines): 5hl 

1> Core-resident pages ere checked for sufficient free 

space. 5hla 

2) Other pages are checked for free space. If one has 

sufficient spacet 1t Is brought yn* 5hlb 

3> If garbage collection on any page In the file will yield 
a page with sufficient free spacet then the page that will 
give the most free space Is brought Into core and 
garbage>*collected ; otherwise a new page is created. 5hlc 
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Detailed Technical Olscussloo 6 

fyote on Fields in A.yGHt.NT Records and Other LIO Language Features 6a 

Several parts of this section are taken directly fro© record 

declarations 1n the code of the AU6NENT system written In the 

LIO programming language* Sal 

Record declarations in the LIO language serve as templates on 

data structures declared In the system* Byte pointer 

Instructions are dropped out by the compiler permitting access 

to specified parts of the array * Multiword records are filled 

frop the lowest to the highest address of the array* Mlthln 

Mordsf bits are allocated from the first bit on the right • If 

several fields fall to fill a 36— bit uord and the next field 

definition would go over the remaining bits In the wordf the 

field 1s allocated 1n the next iiord available* 6a2 

Exaffiple: 632a 

en Is the leftmost bit 1n the word; bit 35 the 

rightmost* Suppose there 1s a record declaration of the 

form: 6a2al 

(newrecordJ RECORD % A two word record % 6a23l3 
fleldlClOl* %b1ts 26 through 35 <r1§htf?iost> of 

first word% 632alal 

f1eld2C253f %b1ts 1 through 25 of first word I Sa2ala2 
f1eld3Ll53l %b1ts 21 through 35 of second word 

Cfleld would not fit 1n remainder of first word% 6a2ala3 

DECLARt arrayl21t 6a2alb 

There may be code within a program of the forra: 6a2a2 

variable _ array*f 1eld2 ? 632a2a 

array •fields _ 201 6a2a2b 

In LlOt false Is zero and true Is nonzero. fea3 

See the LIO manual for further InforRiatlon* 6a4 



lock Header and Types of Blocks 6b 

An AUGHEiyT file 1s iRade up of a file header block page anxi up 

to a fixed nuinber Ccurrently ^65> of 512-iiord 1= one TEWEX 

page> structure block pages Cup to 95> and data block pages Cup 

to 370 >• 6bl 

Each page has a two-word header telling the type and giving the 

file page number and an Index Into a core status table* The 

record declaration from Cnlsbesrct brecordstl follo&^s! 6b2 

Cf1lebLockheader> RECORD %fbhdl = 2 Is length% 6b2a 

fbnullC363f %unused% feb2al 

fb1ndr93f %status table Indexl 6b2a2 

fbpnumC93f %page nutRber 1n file of this block% 6b2a3 

fbtypeC53' %type of this block ftypes declared In 

Cnlsbesrcf bconst»»> 6b2a4 

hdtyp =0 = header 6b2a4a 

sdbtyp = 1 = data 6b2a4b 

rngtyp =2 = ring 6b2a4c 

jnktyp =3 = mlsc Csuch as keyword* vlewchanget etc* 

Mot currently ysed»)% 6b2a4d 

PAGE HEADER BLOCK 

XXXXKXXXKXXXXXKXXKXXXXXXXXXXXXXXXXXXKXKXXXKKXKXXXXKXXXXKIXXX 
X free X 

X 36 X 

X free * Type * Pam * Status X 

K * * MuiBber * Table X 

X 13 * 5 * 9 * 9 X 

XXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXX 

Sb3 

There are several types of block pageSf each with Its own 

structure* 6b4 

File header block pages— always page O: contains general 
Information about the file* 6b4a 

Structure Cr1ng> block pages-Vcontain ring elements that 

Implement the AUGMENT structure: there currently may be a 

maxlffium of 95 of these blocks» each containing 102 five-word 

ring elements* They may appear In file pages 6 through 100» 6b4b 

Data block pages—contain the data properties of AUG^EI^T 

statements: each data page has properties with five-word 

headers fallowed by data Ctextt graphics Instruct lonst 

etc*)* There currently may be a fnaxlFRuas of 370 data pages* 

They may appear In file pages 101 through 471* 6b4c 

Miscellaneous blocks-— not used In the current 

Implementation* 6b4d 



F1'te Header Page 6c 

In ec5ch file* ttrere is a header block page that contains 

general InforiRationt aboat that particular file. The header 

block reiiains "in memory while the file is in use. 6cl 

FILE HEADER CO!\ITENTS Ctaken froiR fnlsbesrc* bdata»l>: 6cla 

DECLARE EXTERNAL Sclal 

I*. .file header«»«% 6cla2 

% DONT CHANGE THE ITEMS IH THE HEADER % 6cla2a 

(filhed) EXTERNAL t43 ? 6cla2b 

% these extra words may be taken for additions to 

header% 6cla2bl 

(fproti EXTERNAL I % protection word % 6cla2c 

Cfcredtl EXTERNAL I % file creation date % 6cla2d 
Cnlsvwdl EXTERNAL = 1 l I nls version word (key wo rd> 

% 6cla2e 

CsidcntI EXTER^.AL ? tcount for' generatinci SIO^sI 6cla2f 

Cfinit> EXTlRISJAL ; % initials at last write % 6cla2§ 

CfunoJ EXTERf^AL ; % user number Cfile owner) % 6cla2h 

atif <0» RH is pointer to string in fiteheaderl Scla2hl 

(lwtif^> EXTERMAL I % last write time % S.cla21 
(naindll) EXTERI^AL I % left naffie delimiter default 

character % 6cl325 
Cnamdl2) EXTEF^MAL % % right name delimiter default 

character % 6cla2k 
Crngl) EXTERNAL I % upper bound on data ring file 

blocks % 6cla2l 
(dtbl) EXTERhlAL * % upper bound on data file 

blocks % 6cl32'R 
(rfbs> EXTERNAL E63 ? %■ start of random file block 

status tables I 6cla2n 

Crngst) EXTERf^AL 1951 t % ring block status table % 6cl32o 

fdtbstJ EXTERMAL E3703 I % data block status table I $cla2p 
Cffikrtsfn> EXTERISIAL = 20 5 % marker table irtaxisRUB 

length X 6cla2q 
(f!ikrtbl> EXTERNAL I % nurRber of markers in marker 

table % 6cla2r 

%each liarker takes HKRL words% 6cla2rl 

(BikrtbJ EXTERMAL C203 I f marker table % 6ola2s 

Cfilhde) EXTERMAL ? tend of the file headerX 6cla2t 

Motes on File Header &clb 

The file header is read into core by the procedure 
Cnlsbesrc* ioexect rdhdr)» This procedure checks for the 
validity of certain keywords* If the file is locked and 
has a partial copy Cthe file that includes current 
modif icat ions—see belowlf the header is read In froiR the 
partial copy* If the partial copy header block is 
invalid in the key spotst the file is unlocked and the 
header read in froro the original file* If that is badt 



the file may be Initialized. ROHDR sets the value of 

f1letieadrf1leno3 where flleno 1s the AUSf^EMT file number 

of the file (an Index Into the file status table which 

provides* aroong other thingsf a correlation between JFMs 

for the original and partial copy and the single AUGFICNT 

file number* see description of the file status table 

below *> 6clbl 

<nlsfoesrc« loexec* setf1l> initializes a file header* Sclb2 

It should be noted that fields within a file header are 

accessed by full word indexing rather then by record 

pointers for speed* Thus we have the following typical 

code CfroiR (nlsbesrct filmnpt crepr2)> that reads the 

default name delimiters froii! an aUGHENT file header: 6clb3 

• 6 c 1 b 3 a 
m 6clb3b 

• 6clb3c 
% Hust calculate the delimiters % 6clb3d 
IF stid.stpsid = origin THIH 6clb3e 

BEGIN luse standard delimiters for that fite% Sclb3el 

fhdloc _ f 1tehesdEst1d»stf1le3 • Sfilhed; &clb3e2 

sdbnew*s IniRdl _ Cfhdloc ♦ Snamdlli; 6clb3e3 

sdbnew»srnB?dl _ Cfhdloc ♦ $namdl21f Sclb3e4 

mo "*' Sclb3e5 

• Sclb3f 

• 6clb3g 

• 6clb3h 

ftlsot code from (nlsbesrct loexect rdhdry that gets the 

address of the word In core that contains the nls version 

word for the file whose header has been read in order to 

check its validity: 6clb4 

• 6clb43 

6clb4b 

&vwd _ Cheader _ filhdrCf1leno>> - Sfilhed + Snlsvwdl 6clb4c 
f1 leheadCfi lenoJ _ header! 6clb4d 

• 6clb4e 

6clb4f 

The file header Is initialized by Cnlsbesrct ioexec* 

rdhdr) which fills up contiguous words declared in 

Cnlsbesrcf bdatatJ and then moves the contents of those 

words to page lerQ of the file. 6clb5 



FILE HEADER BLOCK (FULL yOROSJ 

XKXXXXXKXXXKXXXXXXXXXXXXXXXXX XXXXXXXXXXXXKKXXXX XX XK XXXKXXXX 
X freer 41 XX Hax structure pages X 

X Protection word X X Nax data pages X 

j( — ^ — «-- .^^ — — — X X "■"'* ^ *- — '— -X 

X Creation data X X Start of block tablesC63 X 

X : — ^-. . — ^«— X X" — ■ — ^ — — * — ^- — ^--™-— X 

X Version Number f=l> X X Ring black status tableC953X 

)(« ^.^ .. «- — — » — .« — y X — ■ — — — ^ — ^ — — — ..^ — ■ — ^--K 

X SID Count X X Data blck status tabteC3?03X 

X Initials last write X X Harker table size l-20> X 

X — ~ ^— ™ ^«— -• X K — ^ — : -X 

X File Owner X X Harker tableC201 X 

X — -^ — ^ — ^----.«..««-- ^-. «x X- — ■ ^---— --- — ^-.-- .- X 

X Tlfire last write X X End of file header X 

K Left na«Re del IBS Iter X X X 

X- ^-— .^ -^ ^- ^--..— .X X- — ■ ' ^ — ^- X 

X Right name delimiter XX X 

y XXXX XX XXXXXXXKXX XX XX XXXKXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
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Procedures In Cnlsbesrct flliioptJ are responsible for readlngt 
manlpulatlngt creatlngt garbage collecting* and storing Into 
ring blocks and ring elements within those blocks t and data 
blocks and statement data blocks within thern^ 
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Random File BLock Status Table Entries In File Header &d 

The random file block status tables appear In the file header* 

There is one Mord per rinf block or data block page. Each 

entry contains the followlos; record declaration and cosunents 

from Cnlsbesrcf brecordstK 6dl 

Crfstr) RECORD % random file block status record % 

rfexis flit % true 1f the block exists In the file 

% 

rfpart TII9 % true If block comes frois partial copy 

% 

rfnull C21f % unused % 

rfused C103t X used «ord count for the block % 

rffree ClQ3f % free pointer for the block % 

rfcore r93» X then not In coret else page Index % 

% unallocated 1f entirely zero % 

BLOCK STATUS TABLE ENTRIES CSTRUCTURE OR DATA) 

XKKXKXXXXXXXXXXKXXXXXXXXXXXXXKIXXXJIXXXXXXXXXXXXXXMXXXIXKXKXX 
X * Page Index else * Free * Used * * Part-*Ex1stX 
Kfree* =0 If not In * pointer * word *free* lal * ? X 
K * core * or * count * * copy?* K 

X * * count * * * * X 

X 3 * 9 * 1 ♦10 ♦a* 1 * 1 X 

XXKXXXXXXXXXXXIXXXXXIXXKXKXXXXXXXXXXXXXXXXXXXXXXKXKXXXXXXXMX 

fedlb 

Motes on Random File Block Status Tables 6d2 

The table RFBS In the file header Is broken Into t*#o 
sectionsf each of which contains a collection of records of 
the above type* The first section Includes RMGH entries 

froii RFBSCRWGBASI up to. and Inclu'dlng RFBSrf>NGBA'S4RhlGM-13 

and contains 1nfor»at1on about the ring block pages In the 

file. (RMGBAS Is currently fe and Is the first page In a 

file that way be a ring page? RN6H Is currently 95 and Is 

the roaximum number of ring block pages per»1tted#> 6d2a 

The second section Includes OTBH entries fropi RFBSCDT6BAS3 

up to and Including RFBSCDTBBAS+OTBH^U and contains 

Inforsiatlon about the data block pages In the tile* COTBBAS 

Is currently 101 and Is the first page In a file that »ay be 

a data block page! DTBH is currently 3T0 and Is the (Rajcliiu* 

number of data block pages perinltt ed« > The entry 

RFBSCRNSBAS-*^13 may also be referenced as Rf^0STC13; likewise 

RFBSE0T&BAS*i3 may be referenced as DTBST113. The Index in 

RFBS Is the actual page nurober of a data page In the file* 6d2b 



A pointer to a data eleRient or property CPSDB> consists of a 
nine-bit data page nuwber In the range COtOTSM) and a 
nlne-^blt displacement from the start of the page» The 
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variable DTBL is malrttaloed In each file header as the 
current upper bound on ailcfCated data pages for that file* 
This Is used to Limit the search for a location for a new 
data eleffient# The variable DBLST contains the index of the 
block from which a property was last allocated or freed* 



6d2c 



k pointer to ring element CPSID) consists of a nine-bit ring 
page number in the ranpe COiR^SH) and a nine-bit 
displacement from the start of the page* The variable RM5L 
1s maintained in each file header as the current upper bound 
on allocated ring pages for that file. This is used to 
liiBit the search for a location for a new ring block • The 
variable Rf^SST contains the index of the page from yfiich a 
rinq was last allocated or freed* 



6d2d 
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structure Blocks '-- Ring Eteiaents 



fee 



These blocks contain five-word ring elements with a free list 
cq^nnecting those not 1ri use* 



6el 



C r 1 n g) 

% ■ 



RECORD % *** rlngl Is lertgth% % frorr? Ccompsrct rt-fnain*) 



rsubClB3f %ps1d of sub 

rsucC183f %pSTd of sue 

rsdbfieif %psdb of sdb 

rinstlC73» %OEX Interpo 

rinst2r73t %DEK Interpo 

rdufflmytllf %DEX dummy f 

repetr33f %OEK repetit 

rbftllt %head flag. 

rtfCl3t Xtaii flagt 

rfiaifief r 1 It %naiie flagt 

rtorglnllJf %1nfer1or tr 

rrwlliUf %ynusedl 

rr>aiBehC3Q1t %name hash f 

rs1dt303; % statement i 
%al though only need four 
to orowl 



of this stat stent! 

of this statement % 

for this statement! 
lat Ion string-"- scratch spaced 
I at Ion string-- scratch space% 
lag— scratch space% 
Ion— scratch space% 
true If this Is head of plexl 
true If tall of plex% 
true If statement has a name! 
ee origin flag* true If orlglnX 



or this statement! 

dentif 1er% 

wordsf use five so 



that have room 



■fc Cii 

6e2a 
6e2b 
&e2c 
6e2d 
6e2e 
6e2f 
6e2g 
6e2h 
fee21 
6e2j 
6e2k 
6e2l 
Se2i 
6e2n 
6e2o 
Se2p 



R INS. ELEMENT 
XXXKXXKKXXKXXKXXXMXKKXXXXXXXXKXXJtlKIXKKXXXXXXXKXXXX^CXXXXIXXM 

X PS ID of Successor * PSID of Substate^ent IDown) X 

X 18 * IB X 

X--«-. — ^— : — — -. . : ^ — - — ^-- • — ^ — ^, ■ ^— X 

X Scratch space used by DEX * PSOB ^pointer to data block> X 

X 18 * 18 " X 



Xfree* Masse Hash 
X 1*30 



*f ree*ori *nagie*t a1 1 *headx 
* 1 * 1 * 1 * 1 * 1 X 

■■ X 
X 



X free * Statement Identifier 

X 6 * 30 



X free X 

X 36 X 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 



De3 



PSIOs and PSDBs are pointers to other rinf or data blocks In a 
file* They have two nine-bit fieidsr one Cstblk I Is a pafe 
Index; the other Cst«cl Is a word displacement within that 
page* Procedures In (nlsbesrcf fllianpt* perwit the traversal 
of a f1le*s structure. 



&e# 



Given an STIO (see below)* one iRay use the primitive procedures 
in Cnlsbesrc* f llmnp *>— e»g»» (ntsbesrct fllmnp* getsuO— -or 
the more elaborate procedures in that f1le--e»g** fnlsbesrct 
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fllisnpt getn)ft> — to iRove around to related rin§ eleiiervts and 

retrieve ©r change Cdlsolay &r edit) relevant data. 6e5 

There are two "fixed" values for PSIDs for special 

statements! 6e5a 

The PSID of the origin statement Is always 2* 6e5al 

The entire ST 10 (and hence PSID> of the end of a file 1s 

endfll C=^-l>f yhlch dues not correspond to any real 

statement ^n the filet but which Is returned by the "get* 

procedures In fllmnp to Indicate the end has been reached 

or an error has been found* 6e5a2 

SoBie other conventions iBipleuented In the file structure 

make possible special features 1n AUSNEMi: feeSb 

f'he successor of a statensent with no real successor Is 

its "parent." Se5bl 

The substatei*ent of a statement with no sub 1s Itself* 6e5b2 



The origin Is at a unique level? thus statement 1 Is the 
sub of the origin* 



&e5b3 



lA 



Data Block -- Property Data and Statement Data Blocks 6f 

Property lists are inade up of linked lists of property data 

blocks* An example of a property 5s the Statement Data Block 

CSOBI which contains the text of an AUGHEt^T statement* 6fl 

Each property has a five-word general header with the following 

information* There then follows data appropriate to the 

particular property type. For ejcamplet CTextual) Stateff»ent 

Data Blocks (SOBsl contain the text in AUS^EMT statements; this 

text follows the property header and is composed of seven-bit 

ASCII characters packed five to a word* in a variable length 

block. ^iew properties are allocated in the free space at the 

end of a data p.a^e» Properties no longer in use (because of 

editing changes) are marked for garbage collection when the 

free space is exhausted* 6f2 

(sdbhead) RECORD Isdbhdl is length! % from (compsrcf rt-ma1n»> 

% 6f3 

sgarbnif %true if this sdb is €|8rbage% Sf3a 

slengthi:93f %nuiRber of words in this sdb% 6f3b 

scharsfI113f %number of characters In this statefr?ent% 6f3c 

slnstdltTIf %left name delimiter for statement! 6f3d 

srnffidlC73» %right name delimiter for stateinentl 6f3e 

spsidClSl* %psid of the statement for this sdb% 6f3f 

snaipeClllt %position of character after nasfiel 6f3g 

stiHieC363f Idate and time when this sdb created^ 6f3h 

sinitC211f % initials of user who created this sdbl Sf3i 

sptypeC153f %property type of this data block% 6f35 

% 6f331 

txttyp - text data block CSDBI 6f3f2 

dhdtyp = diagram header block 6f3|3 

segtyp = segment data block 6f3j4 

% Sf3J5 

spsdbClSJf %PSDB of the next property data block 0=tail% Sf3k 

sitpsidCi83? XPSID to head of inferior tree if any% 6f3l 

%sgarb and slength must be In the first word of the header 6f3m 

for newsdb% 6f3n 
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DATA BLOCK HEADER 

XXXXXXXXXXXXXXKXXXXKKXXXXIXXXXKXXXXXXXXXXXKXKXXXKXXXXKKIXXXX 
X *R1ght name *Left name ♦Characters-Block *Garb»X 

X free ^detlmlter *deHfiiter *count ALength^age? X 

X 1 * 7 * 7 ♦ 11 ^9 ♦ 1 X 
x--^ — ^, — . . — . ^- ^ — ^ — -«—,-.-. ^«- ^ — — X 

X free * Position of c^ar * PSID pointer to ring elesent X 

X 7 * 11 after nafise * 18 for this statement X 

X^ . ^ — — ^ ^«- ^«-.«-«-«-.« ; : ^- . ^x 

X Creation time X 

X 36 X 

X — ^ — ^-.-. — ^ «— — ^— ^--. ^«--^ ^ — — ^-x 

X Property * Authors Irtltlals X 

X 15 type * 21 X 

X«— — ^ . ^— «- ^-.-. ^« . ^ — X 

X PS 10 of Inferior tree * PSOB of the r»ext oroperty X 
X IB * 18 X 

XXKXXXXXXXXXXKXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXX 



STATEMENT OATA BLOCK CSOB«S> Text type block 

XXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXX 
X Data black header X 

X 5 full words X 

X TeMt X 

X Block length - 5 yords of 5 characters each X 

XXXIXXXXXXXXXXXXXXXXXXXXXXXXXIXXXXXXXXXXXXKXXXXXXXKXXXKXXXXX 



6f4 



6f5 
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statement Cor String) Identifiers CSTIDS> and Text Pointers 63 

A statement identifier <STID> Is a data structure used within 

AUGMENT to identify AUGMENT statements tstructurat nodesJ or 

strings* 6gl 

If the string is in art AUGMENT statement* the STID contains 

a file identifier field (STFILE) and a ring element 

identifier CSTPSID)* (See PSID description above under 

ring eleiRents») 6fla 

The presence of a file identifier within the STlDper»1t all 
editing functions to be carried out between fi les» 6glb 

Procedures in (nlsbesrct f1lBinpf> permit traversal through the 

ring structure of a file given an STID* Seet for exaiRplet 

Cnlsbesrcf filmnpt getsucJf which gets the STID of the 

successor of a statement; see also lnls« filmnpt getsdbJt 

which returns the STDB for the statement whose STlD is 

provided as an argument* CAn STDB hast like an STIDf a file 

number field and a pointer to the textual property block In 

the property llstf a STPSOB) . Additional primitives are 

available for other data properties. 6g2 

Text pointers are used with the string analysis and 
construction features of L10» They consist of an STID and a 
character count* 6g3 
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other Relevant Arrays 

The following arrays are used in system core and file 
manageRjent* They are described here to facilitate the study of 
the AUGMtf^T file-handling code* 

Fllehe ad 

An array of pointers (each contained In a single word> to 
the file headers of files currently 1n use Is FILEHtAD* At 
present* up to 26 files Cand their partial coplesf If any> 
may be open slaiultaneously* 



CORPST 
Table) 



CCore Pege Status Table! and CRPSAD (Core Page. Address 



6h 

6hX 

6h2 



6h2a 



6h3 



The array CORPST provides the correspondence between the 100 
loctal) pages In core reserved for file pages and user 
program buffer and the pages In files that are currently 
loaded Into core* (This is really a majilffiutfi of 100 octal 
since the user program buffer may be enlarged Into this 
areai the maKlsjum Is fiven by RFPHAX - RFPHIi ■♦-r*) ■ 

(corpgr) RECORD %core page status record! 



ctfull til 9 % true If the page 1s In use t 

ctflle C53f % file to which the page belongs % 

ctpnuffi 191% % page number within the file % 

ctfroz C33? % number of reasons why frozen % 

% a single word; gives status for a fiven core page 

for random files % 



6h3a 

6h3al 
Sh3ala 
6h3alb 
6h3alc 
6h3ald 

6h3aldl 



The array CORPST 1s the core page status table and Is made 
up of Instances of the above record. CsiaxRFP-mlnRFP+l) 
gives the nufRber of core pages that may contain file pages* 
The core pages are located at positions Indicated by the 
array CRPGAD (core page address! • CORPST Is Indexed by 
nuinbers In the range (RFPHINt RFFMAX>» The elements In this 
array are actual addresses* The startlni location of page k 
Is given by crpgadCk3. RFPHIN Is Initialized to be 7; six 
pages are Initially allocated for a user program buffer* 
See Csssrc* prograwstJ for the procedure that changes these 
I Imlts* 



Sh3b 



FILST CFIle Status Table) 



An AUGHFMT file number provides an Indesr Into the FILSTt the 
file status table. This 100-word array Is made up of 25 
four-word entries and contains the following Information for 
files of Interest that have AU6HENT file numbers at any time 
(these fnay or luay not at that time be open? they do% 
however* have JFMs.l The Information cofies from the 
record declaration In CnlsbesrCf breeordsti: 



6h4 



6h4a 
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CfUs 

= fll 

ft 

fi 
ft 
fl 
fl 
wh 
fl 
Co 
ft 
fl 
fl 
f I 
fl 
In 
fl 
by 
fl 
fl 
fl 
fl 
fl 

St 

f I 

na 
fl 



tr> 
stl 

ex1 s 

le % 
head 
brws 
lock 
en I 
PC re 
penp 
accm 
dim 
le I 
nod 
inc I 
dud 
help 
He I 
part 
bpar 
or%g 
astr 

DCSt 

ring 
bpc s 

ne s 
ns« 



RECORD %F1le 
= 4» max n0* 
tl3f % 



191* 
Cllt 
lllf 

oaded % 
ad 1 1 3f 
c) % 

IBI9 
o ri2 3f 

OS [lit 

ude ri3f 

ed % 
ri3f 

p % 

C18 3f 

t C183f 
C183f 

C183» 
% 

t IIBI9 

tring % 
£183; 



X 



% 



status table recordm entry length 
entries = filffiax =25% 6h4al 

true: entry represents an exist ant 

6ti4ala 
crgpad index of the file header % 6h4alb 
this file in browse mode % 6h4alc 

file was locked by another user 

6h4ald 
PC read only-- write open failed 

file access mask % 

directory number for the original 

do not dose this file % 

do not close this file: 1t 1s 

do not close this file: included 



6h4ale 
&h4alf 

6h4alg 

&h4alh 

6h4ali 

feh4alj 
JfH for the partial copy % 6h4alk 

JFN for the browse partial copy t 6h4all 
JFN for the original file % 6h4alm 

address of the file name string I 6h4aln 
address of partial copy name 

6h4alo 

6h4alp 



Cfilstl) EKTER!^ 
ifilmaJt) EXTERN 



address of browse partial copy 
address of nsw filename string % 

AL = filstr.SIzr; 

AL - 25; 



6h4alQ 
Sh4alql 
&h4alq2 
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Primitives for Use «1th Basic AU6HCMT File Entitles 
Introduction 



61 
611 



The following primitives will be available for fBanlpolatlon 
of basic file entities. Whl le they pake use of even more' 
basic proceduresf most prograroaiers should have no reason for 
accessing lower level routines. These primitives and lower 
level procedures live In the file FILMNP* 



SI la 



Property types siiust be assigned numbers by 0A0» Code for 

utanageaient and portrayal of properties not generally 

available or useful for all AUSHEt^T users will be managed 

and written by the prime users* The procedures listed below 

will provide access to property blocks and nodes In the 

files. Sllb 

The code which sianages graphics file entitles lives* 

currentlyt In the graphics subsystem* 61lbl 

Entity types S12 

Prifliltlves will be available to operate on the following 

^ile entity types: 6123 

WOOE — a ring element and Its associated data contained 

In a property list. 6i2al 

PROPERTY *- a data block and any associated Inferior tree 
within the property list associated with a node. 612a2 

If^FERIOR TREE — structure and data associated with a 

property block. S12a3 

An exaitple of the use of an Inferior tree nay be foufid 

In the graphics subsystem In which diagrams have 

structure reflected by the existence of this Inferior 

tree. Another possible use could be for Imposing the 

structure CAUSMEMT Plex-llke In nature) of coiRiRents 

associated with a stateRent»s text. Normal AUSHEMT 

structural procedures for exaiRlnIng structure and 

Htodlfying It at the file level may be used at the 

Inferior tree level as well. 612a3a 

Mote that while no direct primitives are provided for 

operating oh property lists or portions of themt such 

primitives exist at lower levels. It Is not felt that 

higher level primitives for such entitles are necessary. 

The operations listed below follow the currently existing 

examples for text nodes in AUGMEMT files* 612b 

Operands and procedures 613 
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??,EAD — f^ost read functions are dependent on the property 
type and are to be managed by formatters and other specific 
appLleatlon code* Thus a set of "get" and "set" routines 
are available for eKamlnIng and setting fields In the 
stateiBent text nodes and similar procedures eilst In the 
graphics subsystem. A general primitive to load particular 
property types Into core Is provided. Also* the usual 
procedures for moving around In structure will be available* 



613a 



lodprop Cstldt proptype> -- 



613al 



loads the Indicated property block Into core. Returns 
three Items: first Is FALSE If error* page nusifoer In 
core 1f success? second Is address of block In core 
Cwhlch must be frozen 1f you i*ant to do anything with 
1t!)» third Is stdb of property block 



613ala 



f^lote channe: as originally wrlttent lodprop also took 
"occurence" of property In list, we now will not permit 
fRore than one property of a particular type In a 
particular list. Multiple occurences isay be handled by a 
structural Inferior tree hanging off the oroperty block. S13a2 



CREATE -- Allocate space for entity and link the blocks Into 
existing structure and/or data. 



crenod ( st1d» rlevcnt } — 



Gets a new ring element with no associated data blocks 
and links It Into the structure at the location 
specified by stid and rlevcnt Ca relative level count: 
< Is down* =0 Is successor* > is up by rlevcnt 
levels). Returns stid of new r1n<^ or 1f error. 



6.13b 



613bl 



6i3bla 



creprop f stid* proptype* length* data i "-- 



613b2 



Builds a data block of property type proptype which 
must be a valid type assigned iand declared ) by OAD 
and links it into the property list associated with 
the stid In the proper order CdeteriRlned In the 
procedure llnkprop). If such a property already 
exists In the node* we have an error: It must first 
be deleted* Returns stdb of new block or if errc^rm 
length Is the length of the data and data Is a pointer 
to an array of lenpth words In which the data 1s 
stored. 



ere 1t Cst1d* proptype > -- 




ree and links It to 

y stid and 

Id of origin of 



&i3b2a 



S13b3 



613b3a 



DELETE -- Unlink entity frc^m other structure and data. 

Release space. 613c 

delprop f stidf prcptyp > «- 613cl 

deletes the property block and any associated Inferior 
tree structure for the block proptype block of the 
Indicated node* Returns TRUE If successful* If not. 613cla 

dellt Cstid* proptype I -- 613c2 

deletes the Inferior tree of the Indicated property 
block. Unlinks 1t anM releases space. Returns True If 
successfulf If not* 613c2a 

Currently no prlsiltlve exists to directly delete a node* 

though the primitives renigrp and delgrp perform this 

function together. The x-routlnes which Impleinent 

structural deletes call these file system primitives* &13c3 

MOVE -— Unlink entity and relink It at new location In file* 613d 

ffiovprop f stidf proptyp* destld I -- 613dl 

Hoves the property Indicated from node specifed by 

stid to node specified by destid* Accomplishes this 

by unlinking and relinking the block. If a property 

type of the type being aoved exists at the 

destination* we have an error. Returns true If OK* 

If error* 613dla 

jROvIt I stid* proptype* dest1d> -- 613d2 

K»oves the Inferior tree associated with property block 
Indicated by stid and proptype to the property block 
proptype associated with node destid* Returns true If 
OK, If error 613d2a 

K-routlnes currently exist to move and move filtered 

other strucurat entitles* 6l3d3 

COPY -- Allocate space for new entity* copy old entity* and 

link the new entity Into the file* 6l3e 

copprop C stid* proptype* destid ) •"• 613el 

copies property block (and associated Inferior tree If 

&ny> from block Indicated by stid and proptype to a 

new block to be created on destid. Returns TRUE If 

OK. If error 613ela 

citree I stid* proptyp* destid > — 613e2 



22 



copies Inferior tree of property block at node 
Indicated by stid and proptype to the proptype block 
of destid* Returns TRUE If successful t If error 



615e2a 



Priniitlves exist to do structural copies both In filtered 
and unflltered modes. 



613e3 



REPLACE — In keeping with the fRode which exists for text 

statements ♦ a replace primitive ylll not be provided for the 

inferior tree entity or the n&de entity. These functions 

may be accomplished using existing x-rout1nes or primitives 

yhlch delete nodes followed by a copy or create. 6l3f 

reprap (st1d» proptypet lenfthf data> -- 613fl 

replaces the property block Indicated by stid and 

pr opt yp 613fla 



yith a block with data as Indicated* If length Is the 

same as 



6l3flb 



the length of data In the existing property blockt a 

short cut may 613flc 

be taken and the data overwrites the old data. Ift 

howe¥erf 613fld 



the length Is different* a new block Is built and 
linked 1n« 



613fle 



The Inferior tree Is not replaced In any case: 1t 
remains the 



613flf 



same* The Inferior tree's pointer to the ^owning* 

property 613f Ig 

block Is changed to point to the new block. Uses 

fllesc If this Is a text block* 613flh 
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